home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Scope / Scope Disk #121 (199x)(Scope PD)(US)[WB].zip / Scope Disk #121 (199x)(Scope PD)(US)[WB].adf / Post1.1 / post.doc < prev    next >
Text File  |  1990-04-18  |  18KB  |  525 lines
  1. Postscript interpreter - user documentation
  2. ===========================================
  3.  
  4. Post V1.1 Copyright Adrian Aylward 1989, 1990
  5.  
  6. Free use and non-commercial reproduction of the binaries of the interpreter
  7. library (post.library) is permitted, providing that the copyright notices
  8. are not removed.  Distribution by disk libraries is permitted provided only
  9. a nominal copying fee is charged.
  10.  
  11. You may freely copy, use and modify the user interface program (post).  The
  12. source is included in the distribution.
  13.  
  14. All other rights are reserved.  For queries and bug reports write to the
  15. author:
  16.  
  17.         Adrian Aylward,
  18.         20 Maidstone Road,
  19.         SWINDON,
  20.         Wiltshire.
  21.         UK.
  22.  
  23. No responsibilities accepted for bugs, but please let me know so I can fix
  24. them.
  25.  
  26. Introduction
  27. ============
  28.  
  29. "Post" is a software based PostScript interpreter, presently running on the
  30. Amiga.  The source code is written in C, and should be fairly portable to
  31. other machines.  It supports the full Adobe language, with only minor
  32. variations.
  33.  
  34. Prerequisites
  35. =============
  36.  
  37. Post uses the Arp library (V39+), primarily for its file requestor.  For
  38. interactive working you also need ConMan (V1.3+).  Both these programs are
  39. widely available; any good BBS or PD/shareware library should have them.
  40. (ConMan is shareware.)  You may well have them installed on your machine
  41. already.
  42.  
  43. If you prefer not to install ConMan as your standard console handler, you
  44. will need to access it via an alternative device name, which you must
  45. specify by the CONDEV option.
  46.  
  47. You will need at least a megabyte of memory, more for high density printer
  48. output.
  49.  
  50. Command line interface
  51. ======================
  52.  
  53. usage:
  54.     post [files...] [IFF file] [SCREEN] [PRINTER] [INTERACTIVE]
  55.          [SIZE xyd..s..p.bc.] [MEM fhlv..] [CLOSEWB] [CONDEV con]
  56.  
  57. If you forget, type "post ?" to display this.
  58.  
  59. The input files
  60. ---------------
  61.  
  62. The interpreter reads the input files in turn.  When running interactively
  63. the input files are treated as startup files, and are rerun whenever the
  64. interpreter is restarted.  So you would normally specify just the standard
  65. startup file "init.ps", or an alternative of you own.  When running
  66. non-interactively you should in addition specify all the files you want to
  67. interpret, up to 5 in total; when the last is finished the interpreter will
  68. exit.
  69.  
  70. Printer output
  71. --------------
  72.  
  73. This is the default if neither the IFF nor SCREEN options are used, when
  74. running non-interactively.  The output is sent to the printer device as a
  75. graphic dump.
  76.  
  77. The interpreter will obtain default values for the page size, density, and
  78. number of colors from the current preferences.  If you use the default sizes
  79. make sure you have set the page size: run preferences and on the graphic 2
  80. screen set the width and height limits -  either bounded or absolute or in
  81. pixels.  The output defaults to black and white or 3 colour, according to
  82. the preferences.
  83.  
  84. IFF file output
  85. ---------------
  86.  
  87. This option will send the output to an IFF file.  Each IFF file contains a
  88. single FORM ILBM.  So that multiple pages may be created in a single run of
  89. the interpreter, sequence numbers are automatically generated:
  90.  
  91.     IFF path/fred*.pic   will generate  path/fred1.pic, path/fred2.pic ...
  92. and IFF path/fred??.pic  will generate  path/fred01.pic, path/fred02.pic ...
  93.  
  94. The default page size etc. is the same as for screen output.
  95.  
  96. SCREEN output
  97. -------------
  98.  
  99. This option  will send the output to a window on the interactive screen.  It
  100. implies interactive working.
  101.  
  102. You can generate screen, printer and IFF output at the same time.  But since
  103. screen output has to use chip memory and printer output at high resolution
  104. needs a large page buffer (about a megabyte for an A4 page at 300 dpi.) you
  105. will probably run out of memory if you attempt the two simultaneously.
  106.  
  107. The default screen size is the same as the workbench screen, but in
  108. interlace mode.  The default density is 75 pixels per inch.  The default
  109. number of colours is 3.  The page size is rounded up to the maximum size
  110. of the window.
  111.  
  112. The INTERACTIVE option
  113. ----------------------
  114.  
  115. This option causes the interpreter to run interactively.  A screen is opened
  116. and on it appears a requestor window for the parameters.  If you click on
  117. OK two windows will be opened, one for console input and output, and the
  118. other to display the page buffer.  Use the menus.
  119.  
  120. The SIZE option
  121. ---------------
  122.  
  123. The SIZE option sets the page size and density etc..
  124.  
  125.     SIZE "x..y..s..[x]d...[y]d..p.bc.?"
  126.  
  127. The page sizes ("x..y..s..") are in pixels, as decimal numbers; "s" sets
  128. the size of the bands, for band rendering to the printer.  Densities
  129. ([x]d..[y]d..) are in pixels per inch; "xd" or "yd" set the x or y density,
  130. and "d" sets both.
  131.  
  132. The printer density can be set by "p"; its value should be in the range 
  133. 1 to 7.
  134.  
  135. The number of colours is: "b" for black and white (1 bit plane), "c" or "c3"
  136. for 3 colour rgb (3 bit planes), and "c4" for 4 colour cmyk (4 bit planes).
  137.  
  138. The MEM option
  139. --------------
  140.  
  141. The MEM option controls the amount of memory allocated for workspace.
  142.  
  143. The memory defaults are chosen to suit a large machine processing relatively
  144. complex pages.  For simple screen output much lower minimums are possible -
  145. if you don't have enough memory on your machine try the small values
  146. instead.
  147.  
  148.     Default   Small
  149.     -------   -----
  150.     v280000  (80000)     Virtual machine memory
  151.      f60000   (1000)     Font cache
  152.      l60000   (8000)     Line drawing and image workspace
  153.      h20000   (1000)     Halftone buffer
  154.  
  155.      (x + 32) * y / 8    Page buffer
  156.  
  157. The default values should run on a 1MB machine with output to a black and
  158. white screen; for colour output it is necessary to reduce the page size
  159. and/or memory sizes.  On a 2MB machine it should be possible to generate a
  160. complex A4 page of printer output at 300 dpi.
  161.  
  162. The CLOSEWB option
  163. ------------------
  164.  
  165. If memory is tight, you can try using this option to close down WorkBench
  166. while Post is running.  This only works if there are no application
  167. windows open on the WorkBench screen.
  168.  
  169. The CONDEV option
  170. -----------------
  171.  
  172. If you do not have ConMan installed as the default console handler, you
  173. must use this option to specify its device name (without the ":").
  174.  
  175. The WorkBench interface
  176. =======================
  177.  
  178. Just click on the icon.  It always runs interactively.  You can set up
  179. default arguments by setting the ToolTypes; add a string "ARGS=...."
  180. and it will be parsed just like the CLI startup.  For example
  181. "ARGS=init.ps screen" will define the standard startup file and make the
  182. screen the default output.
  183.  
  184. The Menus
  185. =========
  186.  
  187. Project
  188.     Restart              Takes you back to the parameters requestor, after
  189.                          which the interpreter is reinitialised.
  190.  
  191.     Quit                 Quit from the program
  192.  
  193. File
  194.     Load font            Loads a file from the PSFonts: directory by default
  195.  
  196.     Load file            Loads a file, without saving or restoring the VM
  197.  
  198.     Run file             Runs a file, saving VM before and restoring after
  199.  
  200.     Interactive          Interprets interactive input
  201.  
  202. Control
  203.     Pause every page     Toggles pause every showpage/copypage
  204.  
  205.     Continue after pause Does just that
  206.  
  207.     Interrupt            Sends a break; equivalent to CTRL/C
  208.  
  209. Before and after executing a file the operand stack is cleared.  This is
  210. to prevent invalidrestore errors, particularly if interpretation ended in
  211. error with values on the stack.  If you need to leave things on the stack
  212. you will have to run the files from a driver file, or from the interactive
  213. window.  At the end of the file, (after any restore), the page is erased.
  214.  
  215. If you use the automatic font loading, as defined in the standard startup
  216. file "init.ps", the font will be discarded when the VM is restored.  To
  217. avoid repeated reloading of common fonts it may be better to use the "Load
  218. font" menu item to preload the ones you want.  N.B. there is no check to
  219. stop you loading the same one twice; it will probably work but it will
  220. waste memory.
  221.  
  222. Compatability
  223. =============
  224.  
  225. The interpreter is based upon the language (version "23.0") as described by
  226. the (red) book:
  227.  
  228.     "PostScript Language Reference Manual"
  229.     Adobe Systems Incorporated,
  230.     Addison-Wesley 1985, ISBN 0-201-10174-2
  231.  
  232. The 4 colour operators are also supported as described by the document:
  233.  
  234.     "PostScript language Color Extensions"
  235.     Adobe Systems Incorporated (23-Jan-90)
  236.  
  237. File handling
  238. -------------
  239.  
  240. The files %stdin, %stdout, %stderr are permanently open as far as the
  241. operating system is concerned.  Attempts to close them will invalidate the
  242. file object but not close them to the operating system.  If they are
  243. connected to a terminal they will be unbuffered, so output will be
  244. transmitted immediately, without waiting for a "flush".  The special files
  245. %statementedit and %lineedit are not supported.
  246.  
  247. Error handling
  248. --------------
  249.  
  250. A new error "invalidstop" has been added.
  251.  
  252. The execution stack
  253. -------------------
  254.  
  255. The exact contents of the execution stack are not defined by the language
  256. reference manual, and cannot therefore be guaranteed to be the same as other
  257. implementations.  Dumping the stack is likely to yield useful debugging
  258. information but is not recommended for normal programming.
  259.  
  260. Colour mapping
  261. --------------
  262.  
  263. The interpreter can run with one bit plane (for black and white printers),
  264. 3 bit planes (red, green, blue) or 4 bit planes (cyan, magenta, yellow,
  265. black).  For screen output 3 bit planes are appropiate.  For a colour
  266. printer the 3 or 4 colour model can be used.  The output is always in
  267. binary; gray scale is supported only via the halftone mechanism.
  268.  
  269. For low resolution colour printers the 3 colour model is probably best.
  270. The 4 color model is for high resolution colour printers that can generate
  271. high frequency halftone screens, where a fourth screen is used to improve
  272. the quality of the blacks and grays.
  273.  
  274. (N.B. the preferences printer drivers only handle 3 colour model, so if
  275. you want to use the 4 colour model you will probably need to generate an
  276. IFF file and write your own print dump program.  They will however
  277. automatically use black the ribbon/ink if the printer has one)
  278.  
  279. The transformations between the RGB and the HSB models are based on those in
  280. the book:
  281.  
  282.     "Procedural Elements for Computer Graphics"
  283.     David F. Rogers,
  284.     McGraw-Hill 1985, ISBN 0-E07-053534-5.
  285.  
  286. Band Rendering
  287. --------------
  288.  
  289. For a high resolution printer the page buffer can be quite large (a megabyte
  290. or so).  If you don't have enough memory to hold the entire page at once you
  291. can render each one in several bands.  Set the "SIZE s..." option to the
  292. largest band size you have space for.  (For matrix printers it will probably
  293. be best to make it a multiple of the number of printer pins times the number
  294. of vertically displaced passes).  Then run the postscript program generating
  295. each page once for each band, using the "setband" operator, which is
  296. described below, to set the base for each band.  Start at a base of zero
  297. and increment the base by the band size until you reach the page height.
  298. Each band is sent to the printer as a separate graphic dump; the last band
  299. generates a form feed to eject the page.  You can use the "currentband"
  300. operator to calculate the number of bands needed:
  301.  
  302.     currentband 1 sub { setband pageproc } for 0 setband
  303.  
  304. will execute "pageproc" once for each band (remaining) on the page.  The
  305. procedure should execute copypage (or showpage) exactly once per iteration.
  306.  
  307. N.B. this technique is only suitable for printer output.
  308.  
  309. Fonts
  310. -----
  311.  
  312. There are no fonts built in to the interpreter; they must all be downloaded.
  313. The findfont operator will execute the error invalidfont if the font you
  314. request is not present in the font dictionary.  You can redefine it, perhaps
  315. to search the Unix/Amiga filing system to automatically download fonts or to
  316. substitute a default font.
  317.  
  318. The font caching will work significantly better if all your fonts have
  319. UniqueID's.  Then repeated makes of the same font with the same matrix will
  320. be cached, and cached character bitmaps can be retained even if the font
  321. is removed by a restore operation.  N.B. if fonts are downloaded after a
  322. save they will be removed by the corresponding restore; in the interests of
  323. efficiency it may therefore be better to preload them.
  324.  
  325. Other features
  326. --------------
  327.  
  328. Names of the form //name are looked up immediately by the scanner, and
  329. packed arrays have been implemented.  These features were not on the
  330. original Adobe red book, but were added to the language specification later.
  331.  
  332. When scanning the contents of a string, if there any embedded strings the
  333. escape sequences are interpreted just as they are in a file.  This follows
  334. the specification of the more recent Adobe interpreters (including display
  335. PostScript) and not the original red book.
  336.  
  337. Operators omitted or changed
  338. ----------------------------
  339.  
  340.     banddevice
  341.  
  342. Not appropiate for the Unix/Amiga environment.
  343.  
  344.     bytesavailable
  345.  
  346. Since we can't tell how many bytes are available we always return -1.
  347.  
  348.     copypage
  349.  
  350. For printer output this works like the standard.  The number of pages
  351. printed is equal to #copies.  For screen output it does not need to do
  352. anything, as the screen is not buffered.  For IFF file output it writes the
  353. page to the next file.
  354.  
  355.     echo
  356.  
  357. Not appropiate for the Unix/Amiga environment.
  358.  
  359.     executive
  360.  
  361. There is no executive, as the interpreter supports interactive usage
  362. directly.
  363.  
  364.     findfont
  365.  
  366. Looks in the FontDirectory.  If it can't find the supplied key, it executes
  367. the error invalidfont.
  368.  
  369.     flushfile
  370.  
  371. We don't check for errors when flushing an input file, to prevent recursion
  372. in the error handler.
  373.  
  374.     framedevice
  375.  
  376. Not appropiate for the Unix/Amiga environment.
  377.  
  378.     prompt
  379.  
  380. Not called by the interpreter.  See "prompts" instead.
  381.  
  382.     renderbands
  383.  
  384. Not appropiate for the Unix/Amiga environment.
  385.  
  386.     resetfile
  387.  
  388. Does nothing.
  389.  
  390.     showpage
  391.  
  392. See the notes for copypage above.
  393.  
  394.     usertime
  395.  
  396. Returns the time elapsed since the interpreter started, with a resolution of
  397. one second.
  398.  
  399. Operators added
  400. ---------------
  401.  
  402.     currentband
  403.  
  404.         "currentband" base size height
  405.  
  406. Returns the base of the current band, size of each band, and total height
  407. of the page.
  408.  
  409.     setband
  410.  
  411.         base "setband"
  412.  
  413. Sets the base height of the band being rendered.  The value must be greater
  414. than or equal to zero and less than the total height of the page.
  415.  
  416.     invalidstop
  417.  
  418.         (error)
  419.  
  420. A "stop" has been executed for which there is no dynamically enclosing
  421. "stopped" context.
  422.  
  423.     prompts
  424.  
  425.         string string "prompts"
  426.  
  427. The first string is used as the prompt when the interpreter is scanning
  428. terminal input and executing it immediately; the second string is used when
  429. execution is defered while scanning the contents of a procedure "{ ... }".
  430. No prompt is given when a newline is encountered within a string.
  431.  
  432.     vmhwm
  433.  
  434.         "vmhwm" hwmused maximum
  435.  
  436. Returns two integers: the high water mark of the amount virtual memory used
  437. since the program was first started or the last "vmhwm", and the maximum
  438. available amount of memory.
  439.  
  440. Miscellaneous
  441. -------------
  442.  
  443. The system dictionary is left writeable so that standard preludes can add
  444. things to it - possibly removing write permission when they have finished.
  445. Similarly FontDirectory is writeable, so that it is possible to add entries
  446. without using definefont.
  447.  
  448. Device space
  449. ------------
  450.  
  451. The largest device that the interpreter can handle is 31767 (sic) by 32767
  452. pixels.  In practice you will probably run out of memory long before
  453. reaching this limit.
  454.  
  455. Known Bugs
  456. ==========
  457.  
  458. If you close down WorkBench the menus sometimes get truncated and slightly
  459. corrupted.  I suspect this is a Workbench/Intuition problem.
  460.  
  461. If you type CTRL/C to abort if the printer is not ready then strange things
  462. may happen on subsequent attempts to print.
  463.  
  464. N.B. if you run very low on memory, Intuition may behave strangely, and
  465. refuse to resize windows etc..  This is not a bug in Post.
  466.  
  467. Versions
  468. ========
  469.  
  470.     V0.0  14-Nov-89 (prerelease)
  471.  
  472. The original.
  473.  
  474.     V0.1  06-Dec-89 (prerelease)
  475.  
  476. Image routines added.
  477.  
  478. Range checks eased on gray levels and colours etc..
  479.  
  480. Area filling speeded up, matrix manipulation and colour mapping rewritten,
  481. numeric conditioning improved for path fill.
  482.  
  483. Bugs fixed: syntax error, == string escapes, error handling and quit when
  484. recursing, vm error handling, integer overflow in path fill, matrix save,
  485. interrupt after printing page, dictionary second save, name table restore,
  486. boolean type checking, multiple halftone screens memory allocation.
  487.  
  488.     V0.2  07-Jan-90 (prerelease)
  489.  
  490. Font and character routines added.  Null device added.  Band rendering of
  491. printer output added.
  492.  
  493. Matrix manipulation rewritten again.  Interpreter recursion rewritten.
  494. Allocate stacks dynamically.
  495.  
  496. Bugs fixed: missing access checks on strings, scan token negative chars,
  497. depth check in path flattening, pathbbox, strings or null objects as
  498. dictionary keys, shade after grestore(all), fill/image with clip region,
  499. clip unclosed subpath, dictstack/execstack.
  500.  
  501.     V1.0  12-Feb-90
  502.  
  503. Support for big scrollable windows added.  Menu handler added with port
  504. name option.  Workbench startup added with parameters requestor window.
  505.  
  506. Hex string scan optimised.  Break now CTRL/C only, not CTRL/D.
  507.  
  508. Bugs fixed: aspect ratio in iff file, clipping pictures much wider than the
  509. page.
  510.  
  511.     V1.1  27-Mar-90
  512.  
  513. Interpreter made into shared library.  Message port interface removed.
  514. Band printing driver now included.
  515.  
  516. Immediate lookup of //name added.  Packed arrays added.  CR and CRLF now
  517. converted to LF for readline and when scaning tokens from a file.  Copypage
  518. now takes account of #copies. 
  519.  
  520. Bugs fixed: slow images where strings are not rectangles, attributes after
  521. copy and bind, charpath with fonts using gsave, iff run compression,
  522. setundercolorremoval now conforms to Adobe spec, make errorname literal,
  523. slow images repositioned by 1/2 pixel.
  524.  
  525.